home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kcmoduleproxy.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-05-22  |  9.7 KB  |  358 lines
  1. /*  This file is part of the KDE project
  2.     Copyright (C) 2003 Matthias Kretz <kretz@kde.org>
  3.     Copyright (C) 2004 Frans Englich <frans.englich@telia.com>
  4.  
  5.     This library is free software; you can redistribute it and/or
  6.     modify it under the terms of the GNU Library General Public
  7.     License version 2 as published by the Free Software Foundation.
  8.  
  9.     This library is distributed in the hope that it will be useful,
  10.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.     Library General Public License for more details.
  13.  
  14.     You should have received a copy of the GNU Library General Public License
  15.     along with this library; see the file COPYING.LIB.  If not, write to
  16.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.     Boston, MA 02110-1301, USA.
  18.  
  19. */
  20.  
  21. #ifndef KCMODULEPROXY_H
  22. #define KCMODULEPROXY_H
  23.  
  24. #include <qwidget.h>
  25. #include <qstringlist.h>
  26.  
  27. #include <kservice.h>
  28. #include <kdelibs_export.h>
  29.  
  30. class KAboutData;
  31. class KCModule;
  32. class KCModuleInfo;
  33. class KInstance;
  34. class KProcess;
  35.  
  36. /**
  37.  * @ingroup kcmodule
  38.  *
  39.  * @brief Encapsulates a KCModule for embedding.
  40.  *
  41.  * KCModuleProxy is a wrapper for KCModule intended for cases where
  42.  * modules are to be displayed. It ensures layout is consistent, handles
  43.  * root/administrator modules and in general takes care of the details
  44.  * needed for making a module available in an interface. A KCModuleProxy
  45.  * can be treated as a QWidget, without worrying about the details specific
  46.  * for modules such as library loading. KCModuleProxy is not a sub class of KCModule
  47.  * but its API closely resembles KCModule's.\n
  48.  * Usually, an instance is created by passing one of the constructors a KService::Ptr,
  49.  * KCModuleInfo or simply the name of the module and then added to the layout as any
  50.  * other widget. \n
  51.  * When the user have changed the module, changed( bool ) as well as changed ( KCModuleProxy * )
  52.  * is emitted. KCModuleProxy does not take care of prompting for saving - if the object is deleted while
  53.  * changes is not saved the changes will be lost. changed() returns true if changes are unsaved. \n
  54.  * \n
  55.  * KCModuleProxy does not take care of authorization of KCModules. \n
  56.  * KCModuleProxy do lazy loading, meaning the library will not be loaded or
  57.  * any other initialization done before its show() function is called. This means
  58.  * modules will only be loaded when they are actually needed as well as it is possible to
  59.  * load many KCModuleProxy without any speed penalty.
  60.  *
  61.  * KCModuleProxy should be used in all cases where modules are embedded in order to
  62.  * promote code efficiency and usability consistency.
  63.  *
  64.  * @author Frans Englich <frans.englich@telia.com>
  65.  * @author Matthias Kretz <kretz@kde.org>
  66.  *
  67.  */
  68. class KUTILS_EXPORT KCModuleProxy : public QWidget
  69. {
  70. Q_OBJECT
  71.  
  72.     friend class KCModuleProxyRootCommunicatorImpl;
  73.  
  74. public:
  75.  
  76.     /**
  77.      * Constructs a KCModuleProxy from a KCModuleInfo class.
  78.      *
  79.      * @param info The KCModuleInfo to construct the module from.
  80.      * @param withFallback If set to true and loading of the module fails,
  81.      * a alternative will be tried, resulting in the module appearing in its
  82.      * own window, if at all.
  83.      * The embedded module will be load()ed.
  84.      * @param parent the parent QWidget.
  85.      * @param name the module's name.
  86.      * @param args This is used in the implementation and is internal.
  87.      * Use the default.
  88.      */
  89.     KCModuleProxy( const KCModuleInfo & info, bool withFallback = true,
  90.             QWidget * parent = 0, const char * name = 0,
  91.             const QStringList & args = QStringList() );
  92.  
  93.     /**
  94.      * Constructs a KCModuleProxy from a module's service name, which is
  95.      * equivalent to the desktop file for the kcm without the ".desktop" part.
  96.      * Otherwise equal to the one above.
  97.      *
  98.      * @param serviceName The module's service name to construct from.
  99.      * @param withFallback If set to true and loading of the module fails,
  100.      * a alternative will be tried, resulting in the module appearing in its
  101.      * own window, if at all.
  102.      * The embedded module will be load()ed.
  103.      * @param parent the parent QWidget.
  104.      * @param name the module's name.
  105.      * @param args This is used in the implementation and is internal.
  106.      * Use the default.
  107.      */
  108.     KCModuleProxy( const QString& serviceName, bool withFallback = true,
  109.             QWidget * parent = 0, const char * name = 0,
  110.             const QStringList & args = QStringList() );
  111.  
  112.     /**
  113.      * Constructs a KCModuleProxy from KService. Otherwise equal to the one above.
  114.      *
  115.      * @param service The KService to construct from.
  116.      * @param withFallback If set to true and loading of the module fails,
  117.      * a alternative will be tried, resulting in the module appearing in its
  118.      * own window, if at all.
  119.      * The embedded module will be load()ed.
  120.      * @param parent the parent QWidget.
  121.      * @param name the module's name.
  122.      * @param args This is used in the implementation and is internal.
  123.      * Use the default.
  124.      */
  125.     KCModuleProxy( const KService::Ptr& service, bool withFallback = true,
  126.             QWidget  * parent = 0, const char * name = 0,
  127.             const QStringList & args = QStringList() );
  128.  
  129.     /**
  130.      * Default destructor
  131.      */
  132.     ~KCModuleProxy();
  133.  
  134.     /**
  135.      * Calling it will cause the contained module to
  136.      * run its load() routine.
  137.      */
  138.     void load();
  139.  
  140.     /**
  141.      * Calling it will cause the contained module to
  142.      * run its save() routine.
  143.      *
  144.      * If the module was not modified, it will not be asked
  145.      * to save.
  146.      */
  147.     void save();
  148.  
  149.     /**
  150.      * @return the module's quickHelp();
  151.      */
  152.     QString quickHelp() const;
  153.  
  154.     /**
  155.      * @return the module's aboutData()
  156.      */
  157.     const KAboutData * aboutData() const;
  158.  
  159.     /**
  160.      * @return what buttons the module
  161.      * needs
  162.      */
  163.     int buttons() const;
  164.  
  165.     /**
  166.      * @return The module's custom root
  167.      * message, if it has one
  168.      * @deprecated
  169.      */
  170.     QString rootOnlyMsg() const;
  171.     //KDE4 remove. There's a limit for convenience functions,
  172.     // this one's available via moduleInfo()-> and realModule()->
  173.  
  174.     /**
  175.      * @return If the module is a root module.
  176.      * @deprecated
  177.      */
  178.     bool useRootOnlyMsg() const;
  179.     //KDE4 remove. There's a limit for convenience functions,
  180.     // this one's available via moduleInfo()-> and realModule()->
  181.  
  182.     /**
  183.      * Returns the embedded KCModule's KInstance.
  184.      * @return The module's KInstance.
  185.      * @deprecated
  186.      */
  187.     KInstance * instance() const;
  188.     //KDE4 remove. There's a limit for convenience functions,
  189.     // this one's available via realModule()
  190.  
  191.     /**
  192.      * @return true if the module is modified
  193.      * and needs to be saved.
  194.      */
  195.     bool changed() const;
  196.  
  197.     /**
  198.      * Returns whether the module is running in root mode. A module is in root mode
  199.      * when runAsRoot() has been called. A session under root user will never reach
  200.      * root mode.
  201.      *
  202.      * @note realModule() will return null when the module is running in root mode.
  203.      *
  204.      * @return true if the module is running with root privileges
  205.      * @since 3.4
  206.      */
  207.     bool rootMode() const;
  208.  
  209.     /**
  210.      * Access to the actual module. However, if the module is
  211.      * running in root mode, see rootMode(), this function returns
  212.      * a NULL pointer, since the module is in another process. It may also
  213.      * return NULL if anything goes wrong.
  214.      *
  215.      * @return the encapsulated module.
  216.      */
  217.     KCModule* realModule() const;
  218.  
  219.     /**
  220.      * @return a KCModuleInfo for the encapsulated
  221.      * module
  222.      */
  223.     const KCModuleInfo& moduleInfo() const;
  224.  
  225.     /**
  226.      * Returns the DCOP the module's DCOPClient
  227.      * and DCOPObject has(they are identical).
  228.      *
  229.      * @since 3.4
  230.      */
  231.     QCString dcopName() const;
  232.  
  233. public slots:
  234.  
  235.     /**
  236.      * Calling this will cause the module to be run in
  237.      * "administrator mode".
  238.      *
  239.      * @since 3.4
  240.      */
  241.     void runAsRoot();
  242.  
  243.     /**
  244.      * Calling it will cause the contained module to
  245.      * load its default values.
  246.      */
  247.     void defaults();
  248.  
  249.     /**
  250.      * Calling this, results in deleting the contained
  251.      * module, and unregistering from DCOP. A similar result is achieved
  252.      * by deleting the KCModuleProxy itself.
  253.      *
  254.      * @since 3.4
  255.      */
  256.     void deleteClient();
  257.  
  258. signals:
  259.  
  260.     /*
  261.      * This signal is emitted when the contained module is changed.
  262.      */
  263.     void changed( bool state );
  264.  
  265.     /**
  266.      * This is emitted in the same situations as in the one above. Practical
  267.      * when several KCModuleProxys are loaded.
  268.      *
  269.      * @since 3.4
  270.      */
  271.     void changed( KCModuleProxy* mod );
  272.  
  273.     /**
  274.      * When a module running with root privileges and exits, returns to normal mode, the
  275.      * childClosed() signal is emitted.
  276.      *
  277.      * @since 3.4
  278.      */
  279.     void childClosed();
  280.  
  281.     /*
  282.      * This signal is relayed from the encapsulated module, and
  283.      * is equivalent to the module's own quickHelpChanged() signal.
  284.      *
  285.      * @since 3.4
  286.      */
  287.     void quickHelpChanged();
  288.  
  289. protected:
  290.  
  291.     /**
  292.      * Reimplemented for internal purposes. Makes sure the encapsulated
  293.      * module is loaded before the show event is taken care of.
  294.      */
  295.     void showEvent( QShowEvent * );
  296.  
  297.     /**
  298.      * Internal intialization function, called by the constructors.
  299.      *
  300.      * @internal
  301.      * @since 3.4
  302.      */
  303.     void init( const KCModuleInfo& info );
  304.  
  305.  
  306.     /**
  307.      * Emits the quickHelpChanged signal.
  308.      * @since 3.4
  309.      */
  310.     void emitQuickHelpChanged();
  311.  
  312. private slots:
  313.  
  314.    /**
  315.     * Calls the function @p function of the root module's KCModuleProxy
  316.     * DCOP interface.
  317.     *
  318.     * @param function the function signature of the function to call.
  319.     * @since 3.4
  320.     */
  321.     void callRootModule( const QCString& function );
  322.  
  323.     /**
  324.      * This is called when the module exits from root mode. It zeroes
  325.      * pointers, deletes the embed window, and so forth.
  326.      *
  327.      * @since 3.4
  328.      */
  329.     void rootExited();
  330.  
  331.     /**
  332.      * Makes sure the proper variables is set and signals are emitted.
  333.      */
  334.     void moduleChanged( bool );
  335.  
  336.     /**
  337.      * Zeroes d->kcm
  338.      */
  339.     void moduleDestroyed();
  340.  
  341.     /**
  342.      * Gets called by DCOP when an application closes.
  343.      * Is used to (try to) reload a KCM which previously
  344.      * was loaded.
  345.      *
  346.      * @since 3.4
  347.      */
  348.     void applicationRemoved( const QCString& app );
  349.  
  350. private:
  351.  
  352.     class KCModuleProxyPrivate;
  353.     KCModuleProxyPrivate * d;
  354. };
  355.  
  356. #endif // KCMODULEPROXY_H
  357. // vim: sw=4 ts=4 noet
  358.